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

package/dist/plugin-system.d.ts

@@ -4,379 +4,889 @@
  * Core types for the headless plugin architecture.
  * These types define the contract between plugins and the Context Panel UI.
  *
+ * The plugin system uses a **headless** approach: plugins declare metadata
+ * (properties, capabilities, UI config) and the host application renders
+ * appropriate controls automatically in the Context Panel.
+ *
+ * @see {@link PluginConfig} — Top-level plugin definition
+ * @see {@link PropertyDefinition} — How plugins declare editable properties
+ * @see {@link PluginCapabilities} — How plugins declare structural behavior
+ *
  * @package @codefluss/base-types
  * @version 1.0.0
  */
-import type { ComponentType } from "react";
-import type { PluginDesignSystem, PluginUtils } from "./dependencies";
+import type { ComponentType } from 'react';
+import type { PluginDesignSystem, PluginUtils } from './dependencies';
 /**
- * Property control type
- * Defines which UI control to render in Context Panel
+ * Property control type — determines which UI widget the Context Panel
+ * renders for a given property.
+ *
+ * Each value maps to a specific editor control component.
+ * The control's behavior is further configured via the corresponding
+ * field in {@link PropertyUIConfig}.
+ *
+ * @see {@link PropertyUIConfig} for per-control configuration
+ *
+ * @example
+ * ```typescript
+ * // A slider control for font size
+ * const property: PropertyDefinition = {
+ *   key: 'style.fontSize',
+ *   type: 'range',
+ *   label: 'Font Size',
+ *   default: 16,
+ *   ui: {
+ *     control: 'slider',
+ *     slider: { min: 8, max: 72, step: 1, unit: 'px' },
+ *   },
+ * };
+ * ```
  */
-export type PropertyControlType = "input" | "slider" | "select" | "color-picker" | "toggle" | "textarea" | "number-input" | "number-with-unit" | "box-model" | "spacing" | "spacing-combined" | "grid" | "typography-toolbar" | "gradient-editor" | "border-editor" | "font-preset-select" | "color-preset-select" | "text-align-toggle" | "vertical-align-toggle";
+export type PropertyControlType = 'input' | 'slider' | 'select' | 'color-picker' | 'toggle' | 'textarea' | 'number-input' | 'number-with-unit' | 'box-model' | 'spacing' | 'spacing-combined' | 'grid' | 'typography-toolbar' | 'gradient-editor' | 'border-editor' | 'font-preset-select' | 'color-preset-select' | 'text-align-toggle' | 'vertical-align-toggle';
 /**
- * Property type
- * Semantic type of the property value
+ * Semantic type of a property value.
+ *
+ * While {@link PropertyControlType} determines the *UI widget*,
+ * `PropertyType` describes the *semantic meaning* of the stored value.
+ * A single `PropertyType` may be rendered by different controls depending
+ * on the plugin's UI configuration.
+ *
+ * @see {@link PropertyControlType} for the UI control counterpart
+ * @see {@link PropertyDefinition.type}
  */
-export type PropertyType = "text" | "number" | "range" | "select" | "color" | "toggle" | "multiLangText" | "boxModel" | "box-model" | "spacing" | "spacing-combined" | "grid" | "toolbar" | "gradient" | "border";
+export type PropertyType = 'text' | 'number' | 'range' | 'select' | 'color' | 'toggle' | 'multiLangText' | 'boxModel' | 'box-model' | 'spacing' | 'spacing-combined' | 'grid' | 'toolbar' | 'gradient' | 'border';
 /**
- * Property category for organization
+ * Organizational category for properties in the Context Panel.
+ *
+ * Properties are grouped into collapsible sections by category,
+ * providing a consistent editing experience across all plugins.
+ *
+ * - `'content'` — Text, media, and data properties (shown first)
+ * - `'style'` — Visual appearance: colors, typography, backgrounds
+ * - `'layout'` — Spacing, positioning, grid/flexbox settings
+ * - `'advanced'` — CSS classes, ARIA labels, HTML tags, z-index
+ *
+ * @see {@link PropertyDefinition.category}
  */
-export type PropertyCategory = "content" | "style" | "layout" | "advanced";
+export type PropertyCategory = 'content' | 'style' | 'layout' | 'advanced';
 /**
- * Slider control configuration
+ * Configuration for slider UI controls.
+ *
+ * @see {@link PropertyUIConfig.slider}
+ *
+ * @example
+ * ```typescript
+ * const sliderConfig: SliderConfig = {
+ *   min: 0,
+ *   max: 100,
+ *   step: 1,
+ *   showValue: true,
+ *   unit: 'px',
+ * };
+ * ```
  */
 export interface SliderConfig {
+    /** Minimum allowed value */
     min: number;
+    /** Maximum allowed value */
     max: number;
+    /** Increment step between values */
     step: number;
+    /**
+     * Whether to display the current numeric value next to the slider
+     * @default false
+     */
     showValue?: boolean;
+    /**
+     * Unit label displayed after the value (e.g., `'px'`, `'%'`, `'em'`)
+     * @default undefined
+     */
     unit?: string;
+    /**
+     * Discrete labeled positions on the slider track
+     * @default undefined
+     */
     marks?: Array<{
         value: number;
         label: string;
     }>;
 }
 /**
- * Number input control configuration
+ * Configuration for numeric input controls.
+ *
+ * All fields are optional — unset fields inherit sensible browser defaults.
+ *
+ * @see {@link PropertyUIConfig.number}
+ *
+ * @example
+ * ```typescript
+ * const numberConfig: NumberConfig = {
+ *   min: 0,
+ *   max: 9999,
+ *   step: 1,
+ *   unit: 'px',
+ * };
+ * ```
  */
 export interface NumberConfig {
+    /** Minimum allowed value */
     min?: number;
+    /** Maximum allowed value */
     max?: number;
+    /** Increment step */
     step?: number;
+    /**
+     * Unit label displayed after the value (e.g., `'px'`, `'%'`, `'em'`)
+     * @default undefined
+     */
     unit?: string;
 }
 /**
- * Number with unit control configuration (Container-specific)
+ * Configuration for number-with-unit controls (primarily used by containers).
+ *
+ * Unlike {@link NumberConfig}, this control lets the user **switch between
+ * multiple CSS units** via a dropdown alongside the numeric input.
+ *
+ * @see {@link PropertyUIConfig.numberWithUnit}
+ *
+ * @example
+ * ```typescript
+ * // Container max-width control
+ * const config: NumberWithUnitConfig = {
+ *   min: 0,
+ *   max: 9999,
+ *   step: 10,
+ *   units: ['px', '%', 'rem', 'ch', 'vw', 'auto'],
+ *   defaultUnit: 'px',
+ *   allowEmpty: true,
+ * };
+ * ```
  */
 export interface NumberWithUnitConfig {
+    /** Minimum allowed value */
     min?: number;
+    /** Maximum allowed value */
     max?: number;
+    /** Increment step */
     step?: number;
+    /**
+     * Available CSS units the user can select
+     * @default undefined
+     * @example ['px', '%', 'em', 'rem', 'vw', 'vh']
+     */
     units?: string[];
+    /**
+     * Initially selected unit
+     * @default undefined
+     */
     defaultUnit?: string;
+    /**
+     * Whether the field accepts empty / null values.
+     * Typically `true` for container properties like `minHeight` or `maxWidth`
+     * where "auto" or no value is meaningful.
+     * @default undefined
+     */
     allowEmpty?: boolean;
 }
 /**
- * Select control configuration
+ * Configuration for select / dropdown controls.
+ *
+ * @see {@link PropertyUIConfig.select}
+ *
+ * @example
+ * ```typescript
+ * const selectConfig: SelectConfig = {
+ *   options: [
+ *     { value: 'flexbox', label: 'Flexbox' },
+ *     { value: 'grid', label: 'Grid' },
+ *   ],
+ *   searchable: false,
+ * };
+ * ```
  */
 export interface SelectConfig {
+    /** Available options for the dropdown */
     options: Array<{
         value: string;
         label: string;
         icon?: ComponentType;
     }>;
+    /**
+     * Enable type-ahead search filtering for long option lists
+     * @default false
+     */
     searchable?: boolean;
 }
 /**
- * Text input control configuration
+ * Configuration for single-line text input controls.
+ *
+ * @see {@link PropertyUIConfig.input}
  */
 export interface InputConfig {
+    /**
+     * Placeholder text shown when the input is empty
+     * @example 'e.g., custom-class my-style'
+     */
     placeholder?: string;
+    /** Regex pattern for client-side validation */
     pattern?: RegExp;
+    /** Message shown when validation fails */
     validationMessage?: string;
 }
 /**
- * Color picker control configuration
+ * Configuration for color picker controls.
+ *
+ * @see {@link PropertyUIConfig.colorPicker}
+ *
+ * @example
+ * ```typescript
+ * const colorConfig: ColorPickerConfig = {
+ *   format: 'hex',
+ *   alpha: true,
+ *   presets: ['#ff0000', '#00ff00', '#0000ff'],
+ * };
+ * ```
  */
 export interface ColorPickerConfig {
-    format?: "hex" | "rgb" | "hsl";
+    /**
+     * Output color format
+     * @default 'hex'
+     */
+    format?: 'hex' | 'rgb' | 'hsl';
+    /**
+     * Whether to allow alpha (transparency) channel
+     * @default false
+     */
     alpha?: boolean;
+    /** Preset color swatches shown for quick selection */
     presets?: string[];
 }
 /**
- * Textarea control configuration
+ * Configuration for multi-line textarea controls.
+ *
+ * @see {@link PropertyUIConfig.textarea}
+ *
+ * @example
+ * ```typescript
+ * const textareaConfig: TextareaConfig = {
+ *   rows: 1,
+ *   autoResize: true,
+ * };
+ * ```
  */
 export interface TextareaConfig {
+    /**
+     * Initial number of visible text rows
+     * @default 3
+     */
     rows?: number;
+    /**
+     * Automatically grow the textarea height to fit content
+     * @default false
+     */
     autoResize?: boolean;
+    /** Placeholder text shown when empty */
     placeholder?: string;
 }
 /**
- * Box model control configuration
+ * Configuration for box-model (margin/padding) controls.
+ *
+ * Renders a four-sided input (top, right, bottom, left) with
+ * optional linked-sides mode.
+ *
+ * @see {@link PropertyUIConfig.boxModel}
+ * @see {@link SpacingConfig} for the combined margin + padding variant
  */
 export interface BoxModelConfig {
+    /** Minimum value per side */
     min?: number;
+    /** Maximum value per side */
     max?: number;
+    /**
+     * CSS unit for all sides
+     * @default 'px'
+     */
     unit?: string;
+    /**
+     * Whether all four sides are linked (same value) by default
+     * @default false
+     */
     linkedByDefault?: boolean;
 }
 /**
- * Spacing control configuration (combined margin + padding)
+ * Configuration for the combined spacing control (margin + padding in one UI).
+ *
+ * @see {@link PropertyUIConfig.spacing}
+ * @see {@link BoxModelConfig} for individual margin or padding controls
  */
 export interface SpacingConfig {
+    /** Minimum padding value per side */
     paddingMin?: number;
+    /** Maximum padding value per side */
     paddingMax?: number;
+    /** Minimum margin value per side (can be negative) */
     marginMin?: number;
+    /** Maximum margin value per side */
     marginMax?: number;
+    /**
+     * CSS unit for all values
+     * @default 'px'
+     */
     unit?: string;
 }
 /**
- * Typography toolbar control configuration
+ * Configuration for the typography toolbar control.
+ *
+ * Toggles visibility of individual formatting buttons (bold, italic, etc.).
+ *
+ * @see {@link PropertyUIConfig.typographyToolbar}
  */
 export interface TypographyToolbarConfig {
+    /** Show bold toggle button @default true */
     showBold?: boolean;
+    /** Show italic toggle button @default true */
     showItalic?: boolean;
+    /** Show underline toggle button @default true */
     showUnderline?: boolean;
+    /** Show text alignment buttons @default true */
     showAlignment?: boolean;
+    /** Show font size control @default true */
     showFontSize?: boolean;
+    /** Show color picker @default true */
     showColor?: boolean;
 }
 /**
- * Gradient editor control configuration
+ * Configuration for gradient editor controls.
+ *
+ * @see {@link PropertyUIConfig.gradientEditor}
+ *
+ * @example
+ * ```typescript
+ * const gradientConfig: GradientEditorConfig = {
+ *   allowLinear: true,
+ *   allowRadial: true,
+ *   maxStops: 5,
+ *   colorFormat: 'hex',
+ * };
+ * ```
  */
 export interface GradientEditorConfig {
+    /**
+     * Allow linear gradient type
+     * @default true
+     */
     allowLinear?: boolean;
+    /**
+     * Allow radial gradient type
+     * @default true
+     */
     allowRadial?: boolean;
+    /**
+     * Maximum number of color stops
+     * @default undefined (unlimited)
+     */
     maxStops?: number;
-    colorFormat?: "hex" | "rgb" | "hsl";
+    /**
+     * Output color format for gradient stops
+     * @default 'hex'
+     */
+    colorFormat?: 'hex' | 'rgb' | 'hsl';
 }
 /**
- * Border editor control configuration
+ * Configuration for border editor controls.
+ *
+ * @see {@link PropertyUIConfig.borderEditor}
  */
 export interface BorderEditorConfig {
+    /**
+     * Allow editing each border side independently
+     * @default false
+     */
     allowIndividualSides?: boolean;
+    /**
+     * Show border-radius control
+     * @default true
+     */
     allowRadius?: boolean;
+    /**
+     * Maximum border width in pixels
+     * @default 20
+     */
     maxWidth?: number;
 }
 /**
- * Font preset select control configuration
- * Shows typography presets from Design System
+ * Configuration for the font preset select control.
+ *
+ * Displays typography presets from the Design System as a dropdown.
+ * The presets are sourced from {@link PluginDesignSystem.fonts}.
+ *
+ * @see {@link PropertyUIConfig.fontPresetSelect}
  */
 export interface FontPresetSelectConfig {
-    /** Filter fonts by category (e.g., "heading", "body") */
+    /**
+     * Filter fonts by category (e.g., `"heading"`, `"body"`)
+     * @default undefined (show all fonts)
+     */
     category?: string;
-    /** Placeholder text */
+    /** Placeholder text when no preset is selected */
     placeholder?: string;
 }
 /**
- * Color preset select control configuration
- * Shows color presets from Design System (no free text)
+ * Configuration for the color preset select control.
+ *
+ * Displays color presets from the Design System as a dropdown with
+ * optional color swatches. Unlike `color-picker`, this control only
+ * allows preset selection — no free-form color input.
+ *
+ * @see {@link PropertyUIConfig.colorPresetSelect}
  */
 export interface ColorPresetSelectConfig {
-    /** Filter colors by category */
+    /**
+     * Filter colors by category
+     * @default undefined (show all colors)
+     */
     category?: string;
-    /** Placeholder text */
+    /** Placeholder text when no preset is selected */
     placeholder?: string;
-    /** Show color preview swatch */
+    /**
+     * Show a colored swatch preview next to each option
+     * @default true
+     */
     showSwatch?: boolean;
-    /** Allow "None" option for transparent/no color */
+    /**
+     * Allow a "None" option for transparent / no color
+     * @default false
+     */
     allowNone?: boolean;
 }
 /**
- * Alignment toggle control configuration
- * Icon-based toggle buttons for text-align or align-self
+ * Configuration for icon-based alignment toggle buttons.
+ *
+ * Used for both horizontal text alignment (`text-align-toggle`)
+ * and vertical alignment (`vertical-align-toggle`).
+ *
+ * @see {@link PropertyUIConfig.alignmentToggle}
  */
 export interface AlignmentToggleConfig {
-    /** Include justify option for horizontal alignment */
+    /**
+     * Include "justify" option (horizontal alignment only)
+     * @default false
+     */
     includeJustify?: boolean;
-    /** Include stretch option for vertical alignment */
+    /**
+     * Include "stretch" option (vertical alignment only)
+     * @default false
+     */
     includeStretch?: boolean;
-    /** Include auto/inherit option */
+    /**
+     * Include "auto" / "inherit" option
+     * @default false
+     */
     includeAuto?: boolean;
 }
 /**
- * Display mode configuration
+ * Display and layout configuration for a property control in the Context Panel.
+ *
+ * Controls how and when a property is visible, its layout arrangement,
+ * and conditional visibility based on sibling property values.
+ *
+ * @see {@link PropertyUIConfig.display}
+ *
+ * @example
+ * ```typescript
+ * // Show this property only when layout mode is 'flexbox'
+ * const display: DisplayConfig = {
+ *   layout: 'grid-2',
+ *   condition: {
+ *     when: 'layout.mode',
+ *     equals: 'flexbox',
+ *   },
+ * };
+ * ```
  */
 export interface DisplayConfig {
     /**
-     * Show in tooltip on hover vs always visible in panel
+     * Where this property's control is rendered
+     * @default 'panel'
      */
-    mode?: "tooltip" | "panel" | "both";
+    mode?: 'tooltip' | 'panel' | 'both';
     /**
-     * Collapsible section
+     * Whether this property section can be collapsed
+     * @default false
      */
     collapsible?: boolean;
     /**
-     * Default collapsed state
+     * Initial collapsed state (only relevant when `collapsible` is `true`)
+     * @default false
      */
     defaultCollapsed?: boolean;
     /**
-     * Layout mode for property controls in panel (container-specific)
-     * Determines how controls are arranged (single column, 2-column grid, etc.)
+     * Layout arrangement for controls within the panel section.
+     * - `'single'` — one control per row (default)
+     * - `'grid-2'` — two controls side by side
+     * - `'grid-3'` — three controls per row
+     *
+     * Primarily used by container plugins to create compact property grids.
      */
-    layout?: "grid-2" | "grid-3" | "single" | string;
+    layout?: 'grid-2' | 'grid-3' | 'single' | string;
     /**
-     * Conditional visibility based on other property values
-     * @example { when: 'layout.mode', equals: 'flexbox' }
+     * Conditional visibility: show/hide this property based on another
+     * property's current value.
+     *
+     * @example
+     * ```typescript
+     * // Show only when layout mode is 'grid'
+     * { when: 'layout.mode', equals: 'grid' }
+     *
+     * // Show only when border style is NOT 'none'
+     * { when: 'border.style', notEquals: 'none' }
+     * ```
      */
     condition?: {
+        /** Property key (dot-notation) to observe */
         when: string;
+        /** Show this control when the observed property equals this value */
         equals?: unknown;
+        /** Show this control when the observed property does NOT equal this value */
         notEquals?: unknown;
     };
 }
 /**
- * UI configuration for property
- * This is the metadata that tells Context Panel HOW to render
+ * UI configuration metadata for a property.
+ *
+ * Tells the Context Panel **how** to render a property's editor control.
+ * Each property specifies a `control` type and then provides the
+ * matching configuration object (e.g., `slider` config for a `'slider'` control).
+ *
+ * @see {@link PropertyDefinition.ui}
+ * @see {@link PropertyControlType} for the list of available controls
+ *
+ * @example
+ * ```typescript
+ * const ui: PropertyUIConfig = {
+ *   control: 'slider',
+ *   slider: { min: 0, max: 100, step: 1, unit: 'px' },
+ *   display: { layout: 'grid-2' },
+ * };
+ * ```
  */
 export interface PropertyUIConfig {
+    /** Which UI control widget to render in the Context Panel */
     control: PropertyControlType;
+    /** Configuration when `control` is `'slider'` @see {@link SliderConfig} */
     slider?: SliderConfig;
+    /** Configuration when `control` is `'number-input'` @see {@link NumberConfig} */
     number?: NumberConfig;
+    /** Configuration when `control` is `'number-with-unit'` @see {@link NumberWithUnitConfig} */
     numberWithUnit?: NumberWithUnitConfig;
+    /** Configuration when `control` is `'select'` @see {@link SelectConfig} */
     select?: SelectConfig;
+    /** Configuration when `control` is `'input'` @see {@link InputConfig} */
     input?: InputConfig;
+    /** Configuration when `control` is `'textarea'` @see {@link TextareaConfig} */
     textarea?: TextareaConfig;
+    /** Configuration when `control` is `'color-picker'` @see {@link ColorPickerConfig} */
     colorPicker?: ColorPickerConfig;
+    /** Configuration when `control` is `'box-model'` @see {@link BoxModelConfig} */
     boxModel?: BoxModelConfig;
+    /** Configuration when `control` is `'spacing'` or `'spacing-combined'` @see {@link SpacingConfig} */
     spacing?: SpacingConfig;
+    /** Configuration when `control` is `'typography-toolbar'` @see {@link TypographyToolbarConfig} */
     typographyToolbar?: TypographyToolbarConfig;
+    /** Configuration when `control` is `'gradient-editor'` @see {@link GradientEditorConfig} */
     gradientEditor?: GradientEditorConfig;
+    /** Configuration when `control` is `'border-editor'` @see {@link BorderEditorConfig} */
     borderEditor?: BorderEditorConfig;
+    /** Configuration when `control` is `'font-preset-select'` @see {@link FontPresetSelectConfig} */
     fontPresetSelect?: FontPresetSelectConfig;
+    /** Configuration when `control` is `'color-preset-select'` @see {@link ColorPresetSelectConfig} */
     colorPresetSelect?: ColorPresetSelectConfig;
+    /** Configuration when `control` is `'text-align-toggle'` or `'vertical-align-toggle'` @see {@link AlignmentToggleConfig} */
     alignmentToggle?: AlignmentToggleConfig;
+    /** Layout, visibility, and conditional display settings @see {@link DisplayConfig} */
     display?: DisplayConfig;
 }
 /**
- * Property validation rules
+ * Validation rules for a property value.
+ *
+ * Applied client-side when the user edits properties in the Context Panel.
+ *
+ * @see {@link PropertyDefinition.validation}
+ *
+ * @example
+ * ```typescript
+ * const validation: PropertyValidation = {
+ *   min: 0,
+ *   max: 100,
+ *   message: 'Value must be between 0 and 100',
+ * };
+ * ```
  */
 export interface PropertyValidation {
+    /** Regex pattern the string value must match */
     pattern?: RegExp;
+    /** Minimum numeric value */
     min?: number;
+    /** Maximum numeric value */
     max?: number;
+    /** Error message shown when validation fails */
     message?: string;
+    /**
+     * Custom validation function.
+     * Return `true` for valid, or a string error message for invalid.
+     */
     custom?: (value: unknown) => boolean | string;
 }
 /**
- * Property priority for progressive disclosure
- * Determines visual hierarchy and default visibility in Context Panel
+ * Property priority for progressive disclosure in the Context Panel.
+ *
+ * Controls visual hierarchy and default visibility:
+ * - `'quick'` — Always visible at the top, no accordion (most important properties)
+ * - `'common'` — Collapsible section, expanded by default (frequently used)
+ * - `'advanced'` — Collapsible section, collapsed by default (rarely used)
+ *
+ * @default 'common'
+ * @see {@link PropertyDefinition.priority}
  */
-export type PropertyPriority = "quick" | "common" | "advanced";
+export type PropertyPriority = 'quick' | 'common' | 'advanced';
 /**
- * Property definition (headless metadata)
+ * Property definition — the core metadata interface for plugin properties.
+ *
+ * Each plugin declares an array of `PropertyDefinition` objects that describe
+ * its editable properties. The Context Panel reads these definitions and
+ * auto-generates the appropriate editor controls.
+ *
+ * Properties support:
+ * - **Dot-notation keys** for nested data structures (`'style.fontSize'`)
+ * - **Design System integration** via `useGlobal` / `globalKey`
+ * - **Progressive disclosure** via `priority`
+ * - **Conditional visibility** via `ui.display.condition`
  *
- * This is the core interface that plugins use to define their properties.
- * The Context Panel UI reads this and auto-generates appropriate controls.
+ * @see {@link PluginConfig.properties}
+ * @see {@link PropertyUIConfig} for UI control configuration
+ * @see {@link PropertyCategory} for organizational grouping
+ *
+ * @example
+ * ```typescript
+ * const fontSizeProperty: PropertyDefinition = {
+ *   key: 'style.fontSize',
+ *   type: 'range',
+ *   label: 'Font Size',
+ *   default: 16,
+ *   category: 'style',
+ *   priority: 'quick',
+ *   useGlobal: true,
+ *   globalKey: 'fonts.body.size',
+ *   ui: {
+ *     control: 'slider',
+ *     slider: { min: 8, max: 72, step: 1, unit: 'px', showValue: true },
+ *   },
+ * };
+ * ```
  */
 export interface PropertyDefinition {
     /**
-     * Property key (dot notation for nested properties)
-     * @example 'style.fontSize', 'layout.padding.top'
+     * Property key using dot notation for nested data structures.
+     *
+     * This key maps directly to the path in the plugin's `data` object.
+     *
+     * @example 'style.fontSize', 'layout.padding.top', 'contentI18n'
      */
     key: string;
     /**
-     * Property type (semantic)
+     * Semantic type of the property value.
+     * @see {@link PropertyType}
      */
     type: PropertyType;
     /**
-     * Display label for UI
+     * Human-readable label displayed in the Context Panel
      */
     label: string;
     /**
-     * Default value (null = use global default if applicable)
+     * Default value for new plugin instances.
+     * Set to `null` to inherit from the Design System global default
+     * (when `useGlobal` is `true`).
      */
     default: unknown;
     /**
-     * Description shown in UI
+     * Help text / tooltip shown below or beside the control in the UI
      */
     description?: string;
     /**
-     * Property category for organization
+     * Organizational category — determines which panel section this property
+     * appears in.
+     *
+     * @default 'style'
+     * @see {@link PropertyCategory}
      */
     category?: PropertyCategory;
     /**
-     * Whether property is required
+     * Whether a value is required before the element can be saved
+     * @default false
      */
     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
+     * Controls progressive disclosure and default visibility.
+     *
+     * @default 'common'
+     * @see {@link PropertyPriority}
      */
     priority?: PropertyPriority;
     /**
-     * Design System integration
-     * If true, shows "Use Global Default" toggle
+     * Enable Design System integration for this property.
+     * When `true`, the UI shows a "Use Global Default" toggle that
+     * lets the user fall back to the design system value specified
+     * by {@link globalKey}.
+     *
+     * @default false
      */
     useGlobal?: boolean;
     /**
-     * Design System key to reference
+     * Dot-notation path into the Design System to read the global default.
+     * Only used when `useGlobal` is `true`.
+     *
      * @example 'fonts.body.size', 'colors.text-primary'
      */
     globalKey?: string;
     /**
-     * UI control configuration (headless)
+     * UI control configuration — tells the Context Panel which widget
+     * to render and how to configure it.
+     *
+     * @see {@link PropertyUIConfig}
      */
     ui?: PropertyUIConfig;
     /**
-     * Validation rules
+     * Client-side validation rules applied when the user edits this property.
+     * @see {@link PropertyValidation}
      */
     validation?: PropertyValidation;
 }
 /**
- * Plugin metadata
+ * Optional metadata about a plugin, shown in plugin listings and documentation.
+ *
+ * @see {@link PluginConfig.meta}
+ *
+ * @example
+ * ```typescript
+ * const meta: PluginMeta = {
+ *   description: 'Semantic heading component (h1-h6) for page structure and SEO',
+ *   tags: ['heading', 'h1', 'title', 'semantic', 'seo'],
+ *   thumbnail: '/plugins/base-heading/thumbnail.png',
+ *   documentation: 'https://docs.codefluss.com/plugins/base-heading',
+ * };
+ * ```
  */
 export interface PluginMeta {
+    /** Short description of what the plugin does */
     description?: string;
+    /** Search / filter tags for plugin discovery in the editor toolbar */
     tags?: string[];
+    /** Path or URL to a thumbnail image for the plugin browser */
     thumbnail?: string;
+    /** URL to external documentation */
     documentation?: string;
 }
 /**
- * Plugin Capabilities - PLUGIN-DRIVEN ARCHITECTURE
+ * Plugin capabilities — declares **what** a plugin can do structurally.
+ *
+ * This is the core of the **plugin-driven architecture**: each plugin
+ * declares its own capabilities (container vs leaf, allowed children, etc.)
+ * and the application reads these to determine valid operations (drag-drop
+ * constraints, nesting rules, toolbar options).
+ *
+ * @see {@link PluginConfig.capabilities}
+ *
+ * @example
+ * ```typescript
+ * // Container plugin (e.g., base-container)
+ * const containerCaps: PluginCapabilities = {
+ *   supportsChildren: true,
+ *   isRootComponent: true,
+ *   requiresParent: false,
+ *   childrenType: 'nested',
+ *   allowedChildPlugins: [],   // any child allowed
+ *   maxChildren: null,         // unlimited
+ *   minChildren: 0,
+ * };
  *
- * 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.
+ * // Leaf plugin (e.g., base-heading)
+ * const headingCaps: PluginCapabilities = {
+ *   supportsChildren: false,
+ *   isRootComponent: false,
+ *   requiresParent: true,
+ *   childrenType: null,
+ *   allowedChildPlugins: [],
+ *   maxChildren: null,
+ *   minChildren: 0,
+ * };
+ * ```
  */
 export interface PluginCapabilities {
     /**
-     * Can this plugin contain child components?
-     * true = container/layout component
-     * false = leaf component (text, image, button, etc.)
+     * Whether this plugin can contain child components.
+     *
+     * - `true` — container/layout component (e.g., `base-container`, `form-container`)
+     * - `false` — leaf component (e.g., `base-heading`, `base-image`, `base-button`)
      */
     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)
+     * Whether this plugin can be placed at the canvas / section root level.
+     *
+     * - `true` — can be placed directly on the canvas (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
+     * Whether this plugin must be nested inside a parent container.
+     *
+     * - `true` — cannot exist at top level, must be inside a container
+     * - `false` — can be placed directly on the canvas
      *
-     * @example Text component: requiresParent = true (must be in container)
-     * @example Container component: requiresParent = false (can be at top level)
+     * @example
+     * // Text: requiresParent = true (must be in a container)
+     * // Container: 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
+     * Children architecture type (only relevant when `supportsChildren` is `true`).
+     *
+     * - `'nested'` — Children stored as direct arrays in the parent's data (**recommended**)
+     * - `'flat'` — Children reference parent via `parentId` (**deprecated**)
+     * - `null` — Does not support children
      */
-    childrenType: "nested" | "flat" | null;
+    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
+     * Restricts which plugins may be added as children.
+     *
+     * - Empty array `[]` — all plugins allowed as children
+     * - `['base-text', 'base-image']` — only listed plugin IDs allowed
+     *
+     * Only applicable when `supportsChildren` is `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
+     * Restricts which container plugins this plugin may be placed inside.
+     *
+     * - `undefined` or empty array `[]` — can be a child of any container
+     * - `['base-container']` — can only be inside the listed containers
+     *
+     * Only applicable when `requiresParent` is `true`.
      */
     allowedParentPlugins?: string[];
     /**
-     * Maximum number of children allowed
-     * null = unlimited children
-     * number = specific limit
-     * Only applicable if supportsChildren = true
+     * Maximum number of children this container can hold.
+     *
+     * - `null` — unlimited children
+     * - A positive number — enforced limit
+     *
+     * Only applicable when `supportsChildren` is `true`.
      */
     maxChildren: number | null;
     /**
-     * Minimum number of children required
-     * 0 = no minimum requirement
-     * Only applicable if supportsChildren = true
+     * Minimum number of children required by this container.
+     *
+     * Only applicable when `supportsChildren` is `true`.
+     * @default 0
      */
     minChildren: number;
 }
@@ -395,37 +905,60 @@ export interface PluginCapabilities {
  * - Clear separation between editor and view mode
  */
 /**
- * Plugin Dependencies
+ * External dependencies injected into plugin components by the host application.
+ *
+ * Provides access to the Design System, utility functions, and optional
+ * editor callbacks. These are passed via the `dependencies` prop.
  *
- * External dependencies injected by host application.
- * These are provided by the web-app and contain design system,
- * utilities, and callbacks needed by plugins.
+ * **Note:** This is the simplified dependency interface used in `plugin-system.ts`.
+ * The full dependency interface (including `PluginRenderer` component and
+ * `callbacks`) is defined in `dependencies.ts`.
+ *
+ * @see {@link BasePluginProps.dependencies}
+ * @see {@link PluginDesignSystem} for design token access
+ * @see {@link PluginUtils} for utility functions
  */
 export interface PluginDependencies {
     /**
-     * Design System instance
-     * Provides access to fonts, colors, spacing, and other design tokens
+     * Design System instance providing access to fonts, colors, spacing,
+     * breakpoints, and other design tokens.
+     *
+     * @see {@link PluginDesignSystem}
      */
     designSystem: PluginDesignSystem;
     /**
-     * Utility functions
-     * Helper functions for common operations
+     * Utility functions (e.g., `cn` for class name merging)
+     * @see {@link PluginUtils}
      */
     utils: PluginUtils;
     /**
-     * Callbacks (Editor only)
-     * Functions to update element data and properties
+     * Callback invoked when the user edits text content (Editor mode only).
+     *
+     * @param elementId - Unique ID of the element being edited
+     * @param language - ISO language code of the content being changed
+     * @param content - New content value
      */
     onContentChange?: (elementId: string, language: string, content: unknown) => void;
+    /**
+     * Callback invoked when a property value changes via the Context Panel
+     * (Editor mode only).
+     *
+     * @param elementId - Unique ID of the element being edited
+     * @param property - Dot-notation property path (e.g., `'style.fontSize'`)
+     * @param value - New property value
+     */
     onPropertyChange?: (elementId: string, property: string, value: unknown) => void;
 }
 /**
- * Base Props for ALL Plugin Components
+ * Base props required by **every** plugin component.
+ *
+ * Both Editor Components and Renderers must accept these props.
+ * Use the generic parameter `TData` to specify the plugin's data shape.
  *
- * 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 (defaults to `unknown`)
  *
- * @template TData - Plugin-specific data type
+ * @see {@link EditorModeProps} for additional editor-only props
+ * @see {@link RendererProps} for the minimal SSR variant
  *
  * @example
  * ```typescript
@@ -435,36 +968,36 @@ export interface PluginDependencies {
  */
 export interface BasePluginProps<TData = unknown> {
     /**
-     * Unique element ID
-     * Used for data attributes, callbacks, and DOM references
+     * Unique element ID — used for data attributes, callbacks, and DOM references.
+     * @example 'heading-abc123'
      */
     elementId: string;
     /**
-     * Plugin-specific data
-     * Contains all configurable properties and content
+     * Plugin-specific data object containing all configurable properties and content.
+     * The shape is defined by the plugin's type parameter `TData`.
      */
     data: TData;
     /**
-     * Current language (ISO code)
-     * Used for multi-language content resolution
+     * Current language as an ISO code.
+     * Used for resolving multi-language content (`MultiLangContent`).
      * @example 'de', 'en', 'fr', 'es', 'it'
      */
     language: string;
     /**
-     * Injected dependencies
-     * Design system, utilities, and callbacks provided by host application
+     * Injected dependencies from the host application.
+     * @see {@link PluginDependencies}
      */
     dependencies: PluginDependencies;
 }
 /**
- * Editor Mode Props
+ * Additional props for Editor Components only (`'use client'`).
  *
- * Additional props needed ONLY for Editor Components.
- * These props enable interactive editing functionality.
+ * These enable interactive editing: selection highlighting, click handling,
+ * content editing, and property changes. Combine with {@link BasePluginProps}
+ * to form the full editor component props.
  *
- * Editor Components should combine:
- * - BasePluginProps<TData> (required base props)
- * - EditorModeProps (editor-specific features)
+ * @see {@link BasePluginProps}
+ * @see {@link ContainerProps} for additional container-specific props
  *
  * @example
  * ```typescript
@@ -475,40 +1008,54 @@ export interface BasePluginProps<TData = unknown> {
  */
 export interface EditorModeProps {
     /**
-     * Is component currently selected in editor?
-     * Used for visual feedback and activation of editing features
+     * Whether this component is currently selected in the editor.
+     * Used for visual feedback (selection border, handles, etc.).
+     * @default false
      */
     isSelected?: boolean;
     /**
-     * Click handler for component selection
-     * Called when user clicks on the component
+     * Click handler for component selection in the editor.
+     * @param elementId - ID of the clicked element
      */
     onClick?: (elementId: string) => void;
     /**
-     * Content change callback
-     * Called when user edits text content (contentEditable)
-     * @example onContentChange('heading-1', 'de', 'Neuer Titel')
+     * Callback for inline content editing (e.g., `contentEditable` text).
+     *
+     * @param elementId - ID of the element being edited
+     * @param language - ISO language code
+     * @param content - New content value
+     *
+     * @example
+     * ```typescript
+     * 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')
+     * Callback for property changes via the Context Panel.
+     *
+     * @param elementId - ID of the element being edited
+     * @param property - Dot-notation property path
+     * @param value - New property value
+     *
+     * @example
+     * ```typescript
+     * onPropertyChange('heading-1', 'style.fontSize', '32px')
+     * ```
      */
     onPropertyChange?: (elementId: string, property: string, value: unknown) => void;
 }
 /**
- * Renderer Props (View/SSR Mode)
+ * Props for Renderer (SSR / view-mode) components.
  *
- * Minimal props for Server-Side Rendering components.
- * These components do NOT use 'use client' and should work in Node.js environment.
+ * Renderers are **server-safe**: they do NOT use `'use client'`, contain
+ * no React hooks, and receive no editor callbacks. Only the Design System
+ * and utility functions are injected as dependencies.
  *
- * 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 (defaults to `unknown`)
  *
- * @template TData - Plugin-specific data type
+ * @see {@link BasePluginProps} for the full editor variant
+ * @see {@link ContainerProps} for container children
  *
  * @example
  * ```typescript
@@ -524,31 +1071,30 @@ export interface EditorModeProps {
  */
 export interface RendererProps<TData = unknown> {
     /**
-     * Unique element ID
-     * Used for data attributes and DOM references
+     * Unique element ID for data attributes and DOM references
      */
     elementId: string;
     /**
-     * Plugin-specific data
-     * Contains all configurable properties and content
+     * Plugin-specific data containing all properties and content
      */
     data: TData;
     /**
-     * Current language (ISO code)
-     * Used for multi-language content resolution
+     * Current language (ISO code) for multi-language content resolution
      */
     language: string;
     /**
-     * Minimal dependencies (design system and utils only)
-     * No callbacks since renderers are read-only
+     * Minimal dependencies — design system and utilities only.
+     * No callbacks since renderers are read-only.
      */
-    dependencies: Pick<PluginDependencies, "designSystem" | "utils">;
+    dependencies: Pick<PluginDependencies, 'designSystem' | 'utils'>;
 }
 /**
- * Container Props
+ * Props for plugins that support children (containers / layout components).
  *
- * Additional props for plugins that support children (containers, layouts).
- * Used by both Editor Components and Renderers when the plugin has supportsChildren = true.
+ * Used by both Editor Components and Renderers when the plugin has
+ * `capabilities.supportsChildren = true`.
+ *
+ * @see {@link PluginCapabilities.supportsChildren}
  *
  * @example
  * ```typescript
@@ -566,92 +1112,151 @@ export interface RendererProps<TData = unknown> {
  */
 export interface ContainerProps {
     /**
-     * Child components (rendered recursively)
-     * React nodes to be rendered inside this container
+     * Child components to render inside this container.
+     * Provided as React nodes by the recursive element renderer.
      */
     children?: React.ReactNode;
     /**
-     * Drop event handler (Editor only)
-     * Called when user drops an element into this container
+     * Drop event handler (Editor mode only).
+     * Called when the user drags and drops an element into this container.
      *
-     * @param targetId - Container element ID
-     * @param droppedId - Dragged element ID
-     * @param position - Drop position ('before', 'after', 'inside')
+     * @param targetId - Container element ID receiving the drop
+     * @param droppedId - ID of the element being dropped
+     * @param position - Where to insert relative to existing children
      */
-    onDrop?: (targetId: string, droppedId: string, position: "before" | "after" | "inside") => void;
+    onDrop?: (targetId: string, droppedId: string, position: 'before' | 'after' | 'inside') => void;
 }
 /**
- * Plugin configuration (headless)
+ * Complete plugin configuration — the top-level definition object.
+ *
+ * Every plugin registers a `PluginConfig` that describes its component,
+ * editable properties, capabilities, defaults, and metadata. The editor
+ * and runtime use this to render, configure, and constrain plugin instances.
  *
- * Complete plugin definition with component, properties, and metadata.
+ * @see {@link PropertyDefinition} for how properties are declared
+ * @see {@link PluginCapabilities} for structural capabilities
+ * @see {@link PluginMeta} for optional metadata
+ *
+ * @example
+ * ```typescript
+ * const headingConfig: PluginConfig = {
+ *   id: 'base-heading',
+ *   name: 'Heading',
+ *   version: '0.1.0',
+ *   category: 'basic',
+ *   icon: Heading1,
+ *   component: HeadingComponent,
+ *   properties: [ ... ],
+ *   defaults: { contentI18n: { en: 'Heading Text', de: 'Überschrift' } },
+ *   locales: headingLocales,
+ *   ssr: true,
+ *   responsive: true,
+ *   capabilities: {
+ *     supportsChildren: false,
+ *     isRootComponent: false,
+ *     requiresParent: true,
+ *     childrenType: null,
+ *     allowedChildPlugins: [],
+ *     maxChildren: null,
+ *     minChildren: 0,
+ *   },
+ *   meta: { description: 'Semantic heading (h1-h6)', tags: ['heading'] },
+ * };
+ * ```
  */
 export interface PluginConfig {
     /**
-     * Unique plugin identifier
+     * Unique plugin identifier used for registration and lookups.
+     * Convention: `'base-heading'`, `'form-input'`, `'blog-title'`.
      */
     id: string;
     /**
-     * Display name
+     * Human-readable display name shown in the editor toolbar and plugin browser.
+     * @example 'Heading', 'Container', 'Form Input'
      */
     name: string;
     /**
-     * Semantic version
+     * Semantic version string
+     * @example '0.1.0'
      */
     version: string;
     /**
-     * Plugin category
+     * Plugin category — determines which toolbar section the plugin appears in.
+     *
+     * - `'basic'` — Common components (text, heading, image, button, container)
+     * - `'layout'` — Layout-focused components
+     * - `'forms'` — Form-related components (inputs, selects, form container)
+     * - `'advanced'` — Specialized or complex components
      */
-    category: "basic" | "layout" | "advanced";
+    category: 'basic' | 'layout' | 'forms' | '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
+     * Restricts which project types can use this plugin.
+     *
+     * - `undefined` or `[]` — available for ALL project types (default, backward-compatible)
+     * - `['landing']` — only landing page projects
+     * - `['blog']` — only blog projects
+     * - `['landing', 'blog']` — both types
+     *
+     * @default undefined
      */
     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)
+     *
+     * - `'static'` — Content defined at design time (default for most plugins)
+     * - `'dynamic'` — Content bound to a collection entry at runtime (blog posts, shop items)
+     *
+     * @default 'static'
      */
-    contentBinding?: "static" | "dynamic";
+    contentBinding?: 'static' | 'dynamic';
     /**
-     * Icon component (optional)
+     * Icon component rendered in the editor toolbar and plugin browser.
+     * Typically a Lucide icon.
      */
     icon?: ComponentType;
     /**
-     * React component to render
+     * React component to render for this plugin.
+     * Must accept props compatible with {@link BasePluginProps}.
      */
     component: ComponentType<any>;
     /**
-     * Property definitions
+     * Array of property definitions describing editable properties.
+     * The Context Panel auto-generates UI controls from these definitions.
+     *
+     * @see {@link PropertyDefinition}
      */
     properties: PropertyDefinition[];
     /**
-     * Default values for new instances
+     * Default values applied when creating a new instance of this plugin.
+     * Keys correspond to top-level data paths; nested objects are supported.
      */
     defaults: Record<string, unknown>;
     /**
-     * Localized strings for UI
+     * Localized UI strings keyed by locale code (e.g., `{ de: {...}, en: {...} }`).
+     * Used for translating property labels and descriptions in the Context Panel.
      */
     locales: Record<string, unknown>;
     /**
-     * Server-side rendering support
+     * Whether this plugin supports server-side rendering.
+     * When `true`, the plugin should provide a Renderer component
+     * that works without `'use client'`.
      */
     ssr: boolean;
     /**
-     * Responsive design support
+     * Whether this plugin adapts to different viewport sizes.
+     * When `true`, the plugin uses responsive values from the Design System.
      */
     responsive: boolean;
     /**
-     * PLUGIN-DRIVEN ARCHITECTURE:
-     * Plugin capabilities define what the plugin can do
-     * The app reads these to understand how to handle the plugin
+     * Structural capabilities of this plugin — determines nesting rules,
+     * container behavior, and allowed children.
+     *
+     * @see {@link PluginCapabilities}
      */
     capabilities: PluginCapabilities;
     /**
-     * Plugin metadata
+     * Optional metadata for plugin listings and documentation.
+     * @see {@link PluginMeta}
      */
     meta?: PluginMeta;
 }